TRC

man2html: unable to open or read file /usr/lib/ms/ms.acc

NAME

SYNOPSIS

#include "<SOS>/include/trc.h"

DESCRIPTION

trc provides functions for trace output within source programs that can be turned on and off (without recompilation) and that can be divided into different trace levels. Having completed the test phase, the additional code can be eliminated by a compile time switch (compile option -DNO_TT).  

Environment

The standard way to produce trace output is to set the Unix environment variable SOSTRCLEVEL prior to calling a program which uses the trace facility. This variable is interpreted with the call T_INIT (see below). The string to which the tracelevel variable is set consists of a prefix with an arbitrary sequence of items of the following form:

i

turn on indentation (by two blanks)

d o u h

the output format for addresses is decimal(d), unsigned(u), octal(o), or hexadecimal(h)

s

direct trace output to stderr (instead of a file)

n

deactivate trace switch 0; switch 0 is always activated as a default.

<int>

activate all trace switches from 0 to <int>

The remainder of the tracelevel string specifies individual ranges of trace switches to be activated:

#<int>

activate trace switch <int>

#[t]<int>-<int>

activate all switches from the first to the second <int>; if the character t is specified, only trace switches that are multiples of 10 are turned on. If a bound is omitted, it is replaced by 0, or the maximum switch number, respectively.

For example, the Unix csh-command setenv SOSTRCLEVEL id100#214#250-260 turns on indentation mode, makes pointers printed in decimal form, and activates the trace switches 0 to 100, 214, and 250 to 260.  

Trace Output File

The name of the trace output file is given as string parameter to the call of T_INIT. If the named file does not exist, it is created, otherwise truncated. If the tracelevel option s is given, trace output is directed to the screen, instead. The output file will then only contain the starting and ending time of the process. The close-on-exec flag (see fcntl(2)) is set for the trace output file, i.e. a program executed in a subprocess will not write to the same trace output file (unless the name given to T_INIT is the same).

If any trace output is to be written but no output file has been opened by calling T_INIT, a default output file tt.out is opened automatically (see T_INIT).  

Generating Trace Output

The following (cpp) macros are used to generate trace output. These macros are substituted by no code, if the C compiler option -DNO_TT is given. Otherwise they have the following meaning:

T_INIT (name)

interprets the SOSTRCLEVEL environment variable and opens the trace output file that is given by the string name. The default name tt.out is chosen, if name is either NULL, or the empty string.

T_REDEF (tracelevel)

interprets the given string and changes the module settings accordingly. tracelevel is expected to conform to the format described above.

T_EXIT ()

closes the trace output file. The output file is removed, iff the environment contained no definition for SOSTRCLEVEL at the time T_INIT was called.

The deletion of the trace output file in T_EXIT might be unexpected at first. But consider the following program fragment:

int main (int argc, char *argv[])
{  T_INIT ("<prog>.out");
   TTN (0, if (getenv ("SOSTRCLEVEL") == NULL) T_REDEF ("ih#200-"));

   T_EXIT();
   exit (0);
}

If the environment variable SOSTRCLEVEL is not set (note, that trace switch 0 will be activated in this case), the program will choose a default setting and generate a temporary trace output file. This file will be automatically removed in T_EXIT. In case of a fatal program error prior to calling T_EXIT, the output file will still exist and can be used in the error analysis.

TTN (switch, c-statements)

executes the given c-statements if switch has been activated.

TT (switch, c-statements)

behaves like TTN but additionally outputs a newline at the end.

T_PROC (name)

defines a variable char *tt_proc and sets it to the string name which is supposed to name the current function.

T_ENTER, T_LEAVE

both refer to the variable tt_proc and protocol the entrance or leaving of a function.

The following macros output a value of the given type with the given representation:

TB (b)

boolean

TI (i)

int (decimal)

TU (i)

unsigned int (decimal)

TO (i)

int (octal)

TX (i)

int (hexadecimal)

TLI (l)

long int (decimal)

TLO (l)

long int (octal)

TLX (l)

long int (hexadecimal)

TC (c)

character (printable characters are written as such, except for blanks which are written as a double dot (".."); other characters are printed using the C++ escape sequences)

TS (s)

C-string

TSA (s, n)

string array (print first n strings)

TA (a, n)

address (print n bytes starting at a using the format introduced for TC; sequences of identical bytes might be collapsed to a count and the byte)

TP (p)

pointer (printed as specified by SOSTRCLEVEL)

TsS (s)

sos_String; s must be a valid object reference, in particular, NO_OBJECT is not allowed.

TOBJ (o)

sos_Object (print container(), offset()); o == NO_OBJECT is admissible

Additionally, the macro

TXT (s)

can be used to write the string s directly into the trace output file.  

Conventions used for SOS

For a module <m>, there are usually the four trace switches <m>_H, <m>_M, <m>_L, and <m>_VL, standing for high level, medium, low, and very low. Higher levels perform a trace on a more general level; <m>_H will usually generate a trace of the entry/exit of the more important module functions, a lower trace level will add entry/exit of auxiliary functions and a more detailed trace of functions whose entry/exit will appear in the higher trace level. The highest trace level used for a function should include function entry/exit.

The trace switches of a module are defined in a file trc_<m>.h in the module directory of trc, in order to have all trace switches together, thus avoiding duplicate trace switch numbers. Usually, 10 switches are reserved for a module starting with a multiple of 10. Of these, n (<m>_H) up to n + 3 (<m>_VL) are defined for all modules. Note, that traces on a high level can conveniently be activated using the t format option for the tracelevel string (see above).

As far as SOS is concerned, SOS application developers can safely use trace switches 200-499. However, possible conflicts with extensions to the SOS class library should still be taken into account. Currently, trace switch ranges are assigned to the SOS modules as follows:

err

10+

psm

20+

knl

30+

agg

40+

dir

50+

mta

60+

cci

70+

smg

80+

cfe

90+

genCC

100+

All (relevant) function bodies are enclosed in test output; note that inner return statements must be preceded by a T_LEAVE.

int fun (char *s)
{  T_PROC ("fun")
   TT (mdl_H, T_ENTER; TS (s));
   int i;
   ...
   if (...)
   {  ...
      TT (mdl_H, T_LEAVE; TI (i));
      return i;
   }
   ...
   TT (mdl_H, T_LEAVE; TI (i));
   return i;
}

FILES

<SOS>/src/trc/trc.h

include file

<SOS>/src/trc/trc_<m>.h

include file with trace switch definitions for SOS module <m>

<SOS>/src/trc/trc.c

implementation file

<SOS>/lib/sos.a

SOS library

AUTHOR

D. Theobald

Index

NAME

SYNOPSIS

DESCRIPTION

Environment

Trace Output File

Generating Trace Output

Conventions used for SOS

FILES

AUTHOR